One sentence I'd add to the returns section is that for negative values the result is expected to be True, and for positive values False. That won't be completely obvious otherwise to readers not familiar with the low-level details.

@rgommers Isn't that already covered in the special cases section?

    - If ``x_i`` is a positive (i.e., greater than ``0``) finite number, the result is ``False``.
    - If ``x_i`` is a negative (i.e., less than ``0``) finite number, the result is ``True``.

Ref: https://github.com/data-apis/array-api/pull/705/files#diff-153d068dcea18980d39e9465019663509adce3ee4842a48738b37a2a64c693f5R2244-R2245

I assume input shape-preserving is an implicit assumption, given that signbit just follows other elementwise docs?

@leofang That is correct. We don't explicitly mention the expected output shape across the element-wise specifications, but we should probably be explicit. I can submit a follow-up PR to address this more broadly.

Isn't that already covered in the special cases section?

No, special cases are special for a reason, and should not be needed to deduce the main behavior of a function. The text always has to make sense if you'd simply delete the special cases section.

The text always has to make sense if you'd simply delete the special cases section.

IMO this is splitting hairs. The main behavior is precisely as described, as the API should not be confused with the signum function. Meaning, using signbit to test less than or greater than zero is likely an anti-pattern; one can use one of sign, less, or greater instead. Based on a survey of docs,

• PyTorch does not include the requested language.
• NumPy uses misleading language. A value does not have to be less than zero in order for the sign bit to be set.
• CuPy copies over the same misleading description from NumPy.
• Dask copies over the same misleading description from NumPy.
• JAX copies over the same misleading description from NumPy.

It is not a big ask to add something like: "if the sign bit of a value is set, i.e. has value 1 or the value has a minus sign, the result will be False". Or add the math expression like the sign function (x / |x|) for clarity. I didn't ask for fun, I needed to actually double check when I first read it.

@rgommers I've added an extended description.

Two approvals and everyone was happy with this addition, so I'll hit the green button here.